home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / Eval.3 < prev    next >
Encoding:
Text File  |  1994-12-17  |  3.9 KB  |  107 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) Eval.3 1.14 94/12/17 16:17:20
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_Eval tclc 7.0
  12. .BS
  13. .SH NAME
  14. Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. int
  20. .VS
  21. \fBTcl_Eval\fR(\fIinterp, cmd\fR)
  22. .VE
  23. .sp
  24. int
  25. \fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
  26. .sp
  27. int
  28. \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
  29. .sp
  30. int
  31. \fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
  32. .SH ARGUMENTS
  33. .AS Tcl_Interp **termPtr;
  34. .AP Tcl_Interp *interp in
  35. Interpreter in which to execute the command.  String result will be
  36. stored in \fIinterp->result\fR.
  37. .AP char *cmd in
  38. Command (or sequence of commands) to execute.  Must be in writable
  39. memory (\fBTcl_Eval\fR makes temporary modifications to the command).
  40. .AP char *string in
  41. String forming part of Tcl command.
  42. .AP char *fileName in
  43. Name of file containing Tcl command string.
  44. .BE
  45.  
  46. .SH DESCRIPTION
  47. .PP
  48. All four of these procedures execute Tcl commands.
  49. \fBTcl_Eval\fR is the core procedure:  it parses commands
  50. from \fIcmd\fR and executes them in
  51. .VS
  52. order until either an error occurs or it reaches the end of the string.
  53. .VE
  54. The return value from \fBTcl_Eval\fR is one
  55. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  56. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  57. a string with additional information (result value or error message).
  58. This return information corresponds to the last command executed from
  59. \fIcmd\fR.
  60. .PP
  61. \fBTcl_VarEval\fR takes any number of string arguments
  62. of any length, concatenates
  63. them into a single string, then calls \fBTcl_Eval\fR to
  64. execute that string as a Tcl command.
  65. It returns the result of the command and also modifies
  66. \fIinterp->result\fR in the usual fashion for Tcl commands.  The
  67. last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
  68. of arguments.
  69. .PP
  70. \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
  71. its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
  72. a standard Tcl result that reflects the result of evaluating the
  73. file.
  74. If the file couldn't be read then a Tcl error is returned to describe
  75. why the file couldn't be read.
  76. .PP
  77. \fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
  78. processes the command at global level.
  79. This means that the variable context for the command consists of
  80. global variables only (it ignores any Tcl procedure that is active).
  81. This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
  82. .PP
  83. During the processing of a Tcl command it is legal to make nested
  84. calls to evaluate other commands (this is how conditionals, loops,
  85. and procedures are implemented).
  86. If a code other than
  87. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  88. caller should normally return immediately, passing that same
  89. return code back to its caller, and so on until the top-level application is
  90. reached.  A few commands, like \fBfor\fR, will check for certain
  91. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  92. specially without returning.
  93. .PP
  94. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  95. in progress for \fIinterp\fR.
  96. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  97. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  98. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  99. and sets \fIinterp->result\fR to point to an error message indicating that
  100. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  101. invoked in an inappropriate place.  This means that top-level
  102. applications should never see a return code from \fBTcl_Eval\fR other then
  103. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  104.  
  105. .SH KEYWORDS
  106. command, execute, file, global, interpreter, variable
  107.